Toolbar Buttons

How to

... create a command

Commands are created automatically with new buttons. CommandName, CommandText and Text properties are set to bcgBtn*, where * is button ID. When you type button's Text for the first time (e.g. changing the default name), CommandName and CommandText are set to the Text value (note that CommandName can't contain spaces and other special symbols). After that you can modify Text and CommandText in order to customize button's appearance. CommandText appears in Customize dialog.

Note. "Pure" commands (commands not assigned to buttons) can be created in Command Editor.

... quickly create a command handler

Double click on a button in designer. CommandName will be used to automatically build ExecteCommand's handler. ExecuteCommand and UpdateCommandUI handlers are copied at runtime, so you don't need to make any special steps to handle commands sent by buttons created at runtime (during customization).

... assign one command to several buttons (e.g. have a toolbar and menu buttons executing the same command)

Create the first button, then look for its ID property. Create second button (or look for the existing one) and set its ID property to ID of first button.

Note. Use Command Editor to populate buttons from existing commands.

... update button state at runtime

Select a button, set CanUpdateCommandUI property to true. Add handler for UpdateCommandUI event. The handler will be called at idle time. Once the handler is assigned in designer it's copied with the button at runtime. You must cast the sender parameter to a ToolbarButton (or derived class) and set its state:
UpdateCommandUI handler Copy Code
private 
void toolbarButton1_UpdateCommandUI(object sender, EventArgs e)
{
    ((ToolbarButton)sender).Checked = Option;
}
In this case all instances of toolbarButton1 will be updated with the right state.

Note. If in designer you add several buttons with the same ID, you have to assign the same UpdateCommandUI handler manually for all buttons. For example, you may want to do that for a "Copy" button being added to toolbar and context menu.

Also you can handle UpdateCommandUI event fired by CommandBarManager (the designer generates this handler automatically - look for OnUpdateCmdUIHandler in the source code), but here you can get only command ID and update checked or disabled state.
UpdateCommandUI handler Copy Code
private 
void OnUpdateCmdUIHandler(object sender, BCGSoft.ControlBars.UpdateCmdUIEventArgs e)
{
    // Handle UpdateCmdUI here
    if (e.CommandID == 0)
    {
        e.Check = Option;
    }
} 

UpdateCommandUI handler	Copy Code
private void toolbarButton1_UpdateCommandUI(object sender, EventArgs e) { ((ToolbarButton)sender).Checked = Option; }

UpdateCommandUI handler	Copy Code
private void OnUpdateCmdUIHandler(object sender, BCGSoft.ControlBars.UpdateCmdUIEventArgs e) { // Handle UpdateCmdUI here if (e.CommandID == 0) { e.Check = Option; } }

... add images to a button

Use HiColorImage property to set button image. Optionally you can assign menu image (if the button has a large image in toolbar mode). Disabled images are generated automatically, but can be added in designer as well.

Note 1.
It's recommended (due to a bug in Visual Studio) to assign images using the following steps:

1. Select Project | Add Existing Item. From the Add Existing Item dialog add required image(s) to the project.
2. Select image property, click edit button to open Select Resource dialog.
3. Select "Local Resource" | Import...
4. Select desired image.

Note 2
Default transparent color is Magenta.

... change button's state and visibility

Use Enabled and Checked properties. Text and image are shown according to VisualState property. Use Visible property to show or hide a button.

... create a separator

For any button you can set IsSeparator property to true.

... create a toolbar button with arrow. Click on arrow displays a popup menu and click on the button executes a command. Selected command from popup menu "replaces" the default button command.

Create a ToolbarMenuButton on a toolbar. Click the button and add menu items using "Next button...". Select the button on toolbar. Set CanExecuteDefaultCommand property to true. Set button's ID to ID of the first (or any other) button from the popup menu. Add ExecuteCommand handler via events property list.

... add a shortcut

Select a button, select ShortcutsCollection property and open BCGShortcutsEditor dialog.

... add a dummy menu item, which can be expanded in the list of menu items at runtime and can be dragged as a single entity in customize mode

Let's say we would like to add a "Recent File List" to popup menu. Create a ToolbarMenuButton, name it "Recent File List". Go to properties, set IsItemList property to true. Add ExecuteCommand handler. This item will be treated at runtime as expandable list and we can make all commands fired by items routed via this handler. From the open file handler we can add names of opened files to item list:
Add to item list Copy Code
m_commandBarManagerMain.AddToItemList(58, fileName, dlg.FileName); 
Where m_commandBarManagerMain is a reference to CommandBarManager, 58 is ID of the "item list" menu item, fileName is the text we wish to display in the menu, dlg.FileName is the actual name of file. The 3-rd parameter is an user-defined data, which is stored as is in the item (button) and can be retrieved in ExecuteCommand handler:

Add to item list	Copy Code
m_commandBarManagerMain.AddToItemList(58, fileName, dlg.FileName);

OnExecuteCommand handler Copy Code
private 
void RecentFileList_OnExecuteCommand(object sender, BCGSoft.Controls.Shared.ExecuteCommandEventArgs e)
{
    ToolbarButton button = (ToolbarButton)sender;
    m_commandBarManagerMain.RemoveFromItemList(button.ID, button.UserData);
    OpenFile (button.UserData.ToString ());
    m_commandBarManagerMain.AddToItemList(58, button.Text, button.UserData);
} 
The above code removes an item from item list with ID 58 (button.ID) by data (button.UserData), opens the file and adds its name again so it appears first in the list.

In addition you can set the following properties:
MaxItemListDisplayedItems - limits the number of displayed items in the item list
MaxItemListItems - limits the number of items in item list (exceeded items are removed)
NumberItemList - if true, the item text will be prefixed with numbers.

CommandBarManager exposes the following API to manage item lists:
API to manage item lists Copy Code
ToolbarMenuButton^ AddToItemList (int itemListID, String^ itemText, Object^ data);
ToolbarMenuButton^ AddToItemList (int itemListID, String^ itemText);
void RemoveFromItemList (int itemListID, Object^ data);
void ClearItemList (int itemListID);
ArrayList^ GetItemList (int itemListID);
void RenumberItemList (int itemListID);

OnExecuteCommand handler	Copy Code
private void RecentFileList_OnExecuteCommand(object sender, BCGSoft.Controls.Shared.ExecuteCommandEventArgs e) { ToolbarButton button = (ToolbarButton)sender; m_commandBarManagerMain.RemoveFromItemList(button.ID, button.UserData); OpenFile (button.UserData.ToString ()); m_commandBarManagerMain.AddToItemList(58, button.Text, button.UserData); }

API to manage item lists	Copy Code
ToolbarMenuButton^ AddToItemList (int itemListID, String^ itemText, Object^ data); ToolbarMenuButton^ AddToItemList (int itemListID, String^ itemText); void RemoveFromItemList (int itemListID, Object^ data); void ClearItemList (int itemListID); ArrayList^ GetItemList (int itemListID); void RenumberItemList (int itemListID);

... create a special menu entry which handles Window | Window List list.

This is applicable only for MDI interface. MDI child forms must be derived from BCGSoft.Forms.MDIChildForm class.

Create a menu button, name it "Window List". Set property IsItemList to true. Copy ID property of this button, select CommandBarManager component and set its property WindowListButtonID to the copied ID. Now all MDI children will be added to this "item list".

... create a special entry which handles Window Position menu.

"Window Position" is a special library-defined menu containing the following items related to docking panes: Floating, Dockable, Tabbed Document, Auto Hide, Hide. This menu is handled by the library, but you should tell the library about placeholder.

Just create a menu item named "Window Position" and set two properties to true: IsItemList and IsWindowPositionMenu.

... enable "recently used menus"

Currently this option is controlled by MenuBar.UseMRUCommands static member, which is by default set to true. All buttons also created with BasicCommand property set to true. If you wish to remove a button from the basic commands, just set BasicCommand to false.

... customize button appearance

Handle CommandBarManager.DrawCommandObject event. Set Handled property of DrawCommandObjectEventArgs to true.